home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.2 for Intel / NeXTSTEP 3.2 for Intel.iso / NextLibrary / Documentation / Sybase / DBLIB / Section2 / dbgetrow.nr < prev    next >
Encoding:
Text File  |  1993-04-22  |  3.3 KB  |  100 lines
  1. .Na "dbgetrow" 
  2. .Aa
  3. .Fu
  4. Read the specified row in the row buffer.
  5. .Ih "row buffer, reading a row from"
  6. .Sy
  7. .Sf "STATUS dbgetrow(dbproc, row)"
  8. .Sp "DBPROCESS" "*dbproc"
  9. .Sp "DBINT" "row"
  10. .Co
  11. .Bl
  12. .I "dbgetrow()"
  13. sets the current row in the row buffer to a specific row and reads it.
  14. This routine only works if the DBBUFFER option is on, enabling row buffering.
  15. .Ih "DBBUFFER option"
  16. When \f2dbgetrow()\f1 is called,
  17. any binding of row data to program variables (as specified with \f2dbbind()\f1 or \f2dbaltbind()\f1) 
  18. takes effect.
  19. .Bl
  20. Row buffering provides a way to keep a specified number of \*S result rows in program memory.
  21. Without row buffering, the result row generated by each new \f2dbnextrow()\f1 call overwrites the contents
  22. of the previous result row.
  23. Row buffering is therefore useful for programs that need to look at result rows 
  24. in a non-sequential manner.
  25. It does, however, carry a memory and performance penalty because each row in the buffer
  26. must be allocated and freed individually.
  27. Therefore, use it only if you need to.
  28. Specifically, the application should only turn the DBBUFFER option on if it calls \f2dbgetrow()\f1.
  29. Note that row buffering has nothing to do with network buffering and is a completely independent issue.
  30. .Bl
  31. When row buffering is \f2not\f1 enabled, 
  32. the application 
  33. processes each row as it is read from the \*S, by calling
  34. .I "dbnextrow()"
  35. repeatedly until it returns NO_MORE_ROWS.
  36. When row buffering \f2is\f1 enabled,
  37. the application can use
  38. .I "dbgetrow()"
  39. to jump to any row that has already been read from the \*S with
  40. .I "dbnextrow()."
  41. Subsequent calls to
  42. \f2dbnextrow()\f1 cause the application to read successive rows in the buffer.
  43. When \f2dbnextrow()\f1 reaches the last row in the buffer, it reads rows from \*S again,
  44. if there are any.
  45. Once the buffer is full, \f2dbnextrow()\f1 does not read any more rows from \*S
  46. until some of the rows have been cleared from the buffer with \f2dbclrbuf()\f1.
  47. .Bl
  48. The macros \f2DBFIRSTROW()\f1, \f2DBLASTROW()\f1, and \f2DBCURROW()\f1 are useful
  49. in conjunction with \f2dbgetrow()\f1 calls.
  50. \f2DBFIRSTROW()\f1, for instance, gets the number of the first row in the buffer.
  51. Thus, the call:
  52. .ta +4n +4n +4n +4n +4n +4n
  53. .SD
  54. dbgetrow(dbproc, DBFIRSTROW(dbproc))
  55. .ED
  56. sets the current row to the first row in the buffer.
  57. .Bl
  58. For an example of row buffering, see Example 4 in the \f2\*L Reference Supplement\f1.
  59. .Bz
  60. .Pa
  61. .Pi dbproc
  62. A pointer to the DBPROCESS structure that provides the connection
  63. for a particular front-end/\*S process.  It contains all the
  64. information that \*L uses to manage communications and data between the
  65. front end and \*S.
  66. .Pi row
  67. The 
  68. number of the row to read.
  69. Rows are counted from
  70. the first row returned from \*S, whose number is 1.
  71. Note that the first row in the row buffer is not necessarily 
  72. the first row returned from \*S.
  73. .in -.375i
  74. .Re
  75. .br
  76. \f2dbgetrow()\f1 can return four
  77. different types of values:
  78. .Bl
  79. If the current row is a regular row,
  80. REG_ROW is returned.
  81. .Bl
  82. If the current row is a compute row,
  83. the \f2computeid\f1 of the row is returned.
  84. (See \f2dbaltbind()\f1 for information on the \f2computeid\f1.)
  85. .Bl
  86. If the row is not in the row buffer,
  87. NO_MORE_ROWS is returned and the current row is left unchanged.
  88. .Bl
  89. If the routine was unsuccessful, FAIL is returned.
  90. .Bz
  91. .Sa
  92. dbaltbind,
  93. dbbind,
  94. dbclrbuf,
  95. DBCURROW,
  96. DBFIRSTROW,
  97. DBLASTROW,
  98. dbnextrow,
  99. options
  100.